home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 157_01 / qe123.doc < prev    next >
Text File  |  1987-10-10  |  13KB  |  266 lines
  1. DOCUMENTATION FOR EDITOR QE AND QED Version 1.23
  2.  
  3. DATE:     29 APRIL 1986
  4. VERSION:  1.23
  5. AUTHORS:  Nigel Gilbert and James Haefner
  6.  
  7.     This report documents changes made in the screen editor 
  8. QE for BDS C (tm) (version 1.50a) and QED for DeSmet C (tm) 
  9. (version 2.41).  I assume the reader is familiar with 
  10. previous documentation for the editor 'e' and the 
  11. documentation file QE/D.DOC for version 1.0 of the QE and 
  12. QED editors.
  13.  
  14. CHANGES COMMON TO QE AND QED
  15.  
  16.     The following changes apply to both the CP/M and MSDOS 
  17. versions.
  18.  
  19.     1.    WORD WRAP.  Automatic word wrapping has been added.  When 
  20. text input reaches a prescribed column, the editor will break 
  21. the current line between words, insert a carriage return at the 
  22. end, and continue to permit input on the next line.  The column 
  23. for wrapping is set in the editing context screen (^QKR).  In 
  24. addition, there are two methods for reformatting existing text 
  25. to fit within a specified column setting.  First, a "quick" 
  26. single paragraph reform function has been added to reformat a 
  27. paragraph from the current line on which the cursor lies to the 
  28. end of the paragraph.  Since "hard" (sensu WordStar) carriage 
  29. returns are appended to each line, the end of a paragraph is 
  30. the line above (a) a blank line (no text), (b) a line that 
  31. begins with white space, or (c) the end of the file.  The 
  32. commands for this method are ^QP (for "prettify paragraph"). 
  33.  
  34.     The second method to reform text is via the "block" commands, 
  35. where an option has been added to permit a defined block to be 
  36. reformed to fit within a specified right margin.  The
  37. commands for this method are: ^KBR, followed by the definition 
  38. of the text block.  The second method will not reform across 
  39. paragraghs (i.e., concatenate text of several paragraphs), if 
  40. the paragraphs are defined by separating empty lines of text.  
  41. "Paragraphs" separated only by leading white space on the first 
  42. line of succeeding paragraphs will be converted into a single 
  43. paragraph. 
  44.  
  45.     Reformatting may be turned off in two ways.  First, the 
  46. header file, QE.H, contains a "#define WWRAP (YES)" 
  47. statement that will permit or prohibit compilation of the 
  48. relevant code.  Second, the editing context screen (via 
  49. ^QK) permits setting of the right margin.  If the right 
  50. margin is 255 (current value of the maximum line length), 
  51. reforming is effectively turned off, as any attempts to 
  52. input text beyond this column results in a truncated line, 
  53. as in the original 'e'.
  54.  
  55.     New functions for word wrapping have been added to QE2 
  56. and QE6, with minor additions to QE1, QE, and QE4.  QE6 
  57. contains "reform()" which does most of the work; QE2 
  58. contains "char *firstwhite()", which returns the address of 
  59. the first non-white character from the right-hand end of 
  60. the current line.  The latter function is used both during 
  61. block reforming and reforming that occurs when inserting 
  62. text.
  63.  
  64.     2.    VERSION DOCUMENTATION.  Unadulterated CP/M, as we 
  65. all know, does not record the date and time of file 
  66. formation or alteration.  I have added code that minimizes 
  67. the effort required to update a commented line at the 
  68. beginning of the file indicating the version number, 
  69. current date, and current time.  If no version 
  70. documentation line exists, one is added.  If this is the 
  71. case, the user is prompted for the set of comment 
  72. delimiters in which to enclose the line.  Thus, for a file 
  73. to be used as input to the ROFF4 formatter we have this 
  74. line at the top of the file:
  75.  
  76. ..  VERSION 0003  (DATE: 13/10/86)  (TIME: 22:09)  ..
  77.  
  78.     The code has been structured such that, if a clock on 
  79. CP/M systems is available, the user can insert code to 
  80. determine the date and time with no user input.  Most MSDOS 
  81. systems seem to have clocks (even if they have no battery 
  82. backup), so for those systems, date and time are determined 
  83. via DOS calls and no user input is required.  The version 
  84. number is incremented automatically.
  85.  
  86.     CP/M users with no clock (like myself) must provide the 
  87. necessary information, which is a pain, but I have 
  88. attempted to make it as easy as possible.  The date and 
  89. time are stored as five bytes in the CP/M zero page at 
  90. location NOWLOC, which is currently set to 50 hex.  In both 
  91. of my systems, this location is not overwritten by normal 
  92. program execution.  In fact, one of the BIOSes does not 
  93. even zero these locations on a physical reset.  In any 
  94. case, the appropriate values may need to be set for 
  95. different systems, but if 5 contiguous safe locations exist 
  96. anywhere in memory (including high memory, above BDOS), 
  97. then the date and time should persist through exit and 
  98. re-entry to the editor.
  99.  
  100.     No user input is required in QED on MSDOS systems, once the 
  101. initial version comment line has been inserted.  On CP/M 
  102. systems without clocks, only the current date and time strings 
  103. must be edited on the status line during a file save operation.  
  104. Depending on the time period since the last power down or 
  105. system reset and the last alteration of the file, this can 
  106. involve as little as changing the single character on the 
  107. status line that is the last digit of minutes.  If you wish to 
  108. update only the version number and leave the date and time as 
  109. they are, then pressing <CR> twice (for date and for time) will 
  110. leave these unchanged.  In general, typing a carriage return 
  111. will leave the requested information (i.e., the date or time) 
  112. unchanged.  The editing possibilities for the entry are 
  113. identical to string searching; in particular, backspacing, 
  114. altering a character, then typing ^L will alter the character 
  115. and replay the remainder of the entry.  
  116.  
  117.     Inclusion of this code is controlled by "#define VRSNNUM 
  118. (YES)" and "#define VRSNDATE (YES)" statements.  Thus, 
  119. users not wishing this feature may exclude it.  (Check 
  120. these settings in QE.H before compiling.)  In addition, 
  121. version update on a file may be frustrated within the 
  122. editor via the editing context screen (^QKV).  If you 
  123. forget to turn off version updating globally via ^QK, you 
  124. can still prevent version updating by typing '~' at the 
  125. prompt for a left comment symbol (no previous version 
  126. comment line) or at the prompt for the current date.
  127.  
  128.     This facility seems to be relatively useful, especially in 
  129. CP/M, but the user should be prepared to suffer some 
  130. embarrassment upon showing to friends listings of difficult 
  131. programs that have endured many editing-compile cycles and, 
  132. thus, have large version numbers.  You will see some of these in 
  133. the source code of QE.
  134.  
  135.     All of the code for version documentation is in the new 
  136. files QE11 and QED11.
  137.  
  138.     3.  RV UTILITY.  I also include a short utility to report the 
  139. version number for a set of CP/M files.  The command line 
  140. syntax is: 
  141.  
  142.     rv [-cd] ambigfilename
  143.  
  144. where -c means compare the version numbers of the files on 
  145. the current drive with those of the same names on drive 
  146. 'd'.  "Ambigfilename" is a set of ambiguous filenames 
  147. according to the convention of "wildexp()", which is 
  148. required.  E.g., to list on the console the version 
  149. comments of all the QE text files and compare with those on 
  150. drive B, do this:
  151.  
  152.     A>rv -cb QE*.* !QE*.CRL !QE*.COM
  153.  
  154.     This utility has obvious applications to maintaining 
  155. backups of current versions.  Remembering which CRL and COM 
  156. files to backup is the responsibility of your own personal RAM.
  157.  
  158.     4.    EXPERT MODE.  The verbose prompts for various command 
  159. options (e.g., block movement) can be replaced with a terse 
  160. list of letter options on the statusline that does not 
  161. overwrite the displayed text.  This is the current default 
  162. condition when the editor is loaded (change this default in 
  163. QED.C).  It can be toggled on and off on the command line (-E), 
  164. or in the "editing context screen" (^QKE). 
  165.  
  166.     5.    SCROLLING.  Speed of scrolling has been increased.
  167.  
  168.     6.  LINE UNDELETE.  A line deleted via ^\ or a partial 
  169. lined deleted from the current cursor to the end of the 
  170. line using ^QY is stored in a buffer.  This buffer can be 
  171. inserted below any other line using ^^.  This permits 
  172. an easier method of moving single lines w